HTML Migration

Migration of the Wiki is almost complete. These notes will serve to help migrate HTML text to DokuWiki in the future. — Rick Gleason 2017/01/17 14:45

Summary of Progress Reporting

Please report each book's progress with a brief report of what you did, with initials, by editing this page.This will give others a chance to know what to do next!! Very important so we don't duplicate efforts. Thanks.

Summary of Progress

PS: You can also use the bottom Summary field provided on each page before you save it. Might be very effective.

Migration Process

1. Duplicate Book Outline and Create Pages
2. Copy all of a Books/Namespaces Media files to the Owiki
3. Copy all of a Books/Namespaces Text(HTML) files to the Owiki
4. Check Formatting Syntax and Improve text and legibility
5. Redirect Media links. Check all Media links on each page.
6. Redirect internal links. Check all internal links on each page
7. Pathnames & Namespaces - Portability.
8. Table of Contents - Indexmenu Plugin & File Structure creates the TOC
9. Correct Footer on all Pages. Actually remove all footers!
10. Final Check of Formatting Syntax. Improve text and legibility
11. Check all links
12. Done

←—For instructive Editing pages Under Editors Manual and see HTML Migration

1. Duplicate Book Outline and Create Pages.

  1. I've done most of this in preparation for the “barn raising”.
  2. If you see Red links, the link is there, but the page is not created yet. More on that later.
  3. There are some pages missing under Developer Manual and I am finding pages in the original wiki that are not in the navigation outline. Yesterday I found 3.
  4. For questions refer to Editor User Manual Notes or PM rgleason or email me.
  5. I will try to improve this page and the process. Editors may edit it too.
  6. Typical Page Header Code - Edited in DW Edit
{{indexmenu_n>1}}
====== Developer Guide ======

Internal Links (unordered list)
  * [[opencpn:developer_manual:developer_guide:compiling_linux|Compiling Linux]]
  * [[opencpn:developer_manual:developer_guide:compiling_windows|Compiling Windows]]
           Note: Full path from [[opencpn:_-->]]  onward is required.

Media Links

 {{opencpn:dev:logo.png}}
 {{opencpn:dev:ologo-60x60.png|oLogo 60x60}} <--Adds "|" with hover text}}
 {{opencpn:dev:ologo-60x60.png?30|oLogo 60x60}} <-- Resize adding "?30" or "?30x30"
            Note Full path from {{opencpn:_-->}} please

Line 1 = Index sort order used by the Indexmenu Plugin
Line 2 = Page Title and TOC text for the left navigation TOC.
Line 3 = Internal Page link.  All internal links must start with
         "[[opencpn:_" and continue with the full path to and including the page.
         The page name should be lower case with _ for spaces.
Line 3 = Pipe "|" separates the internal link from the visible Link Title (if there
         is no pipe and Link Title the internal link will be shown)
line 4 = Media Link, a link to an image, shows the image.
Line 5 = Media Link, a link to an image.

Internal Link Examples (unordered list):

Image Link Examples:


{{opencpn:dev:logo.png}}

opencpn:dev:logo.png–size is 100×100, image is shown full size


{{opencpn:dev:ologo-60x60.png}}

opencpn:dev:ologo-60×60.png–size is 60×60 (which happens to be reflected in the name), image is shown full size


{{opencpn:dev:ologo-60x60.png?30}}

opencpn:dev:ologo-60×60.png?30–Uses the same file as the previous image but has been resized to 30×30

2. Copy all of a Books/Namespaces Media files to the Owiki.

  1. Open one of the old books in your browser, say Developer Manual and right-click save-as each image to a temporary download directory on your PC starting at the first page, and working all the way to the end. Some images are links. You'll recognize them if your mouse pointer changes to a hand when you hover over them. If so you need to click on the image in the page to reach the underlying image file.
  2. Then in a new Browser Tabb, log into the Owiki temporary website, open “Media Manager”, and navigate Media Manager to the opencpn:dev directory. It's important to upload the images to the media directory that matches the book you are editing.
  3. Media Directories Place the image files in correct directory.
    • Developer Manual - opencpn:dev
    • Supplementary Hardware - opencpn:hardware
    • Supplementary Software - opencpn:software
    • Opencpn User Manual - opencpn:manual (Done)
  4. Now comes the easy part. In Media Manager, Select Upload Tab and browse to your PC's temporary download directory. Select all the files and upload them to the Owiki media directory opencpn:dev
  5. Check to make sure all the files are uploaded by trying to upload again.The Media Manager will skip files already uploaded.
  6. Then delete the files in your PC temporary directory, as you may use it again.
  7. The media files for one book have now been moved to Owiki and in other steps , be “linked” to with the proper pathname/imagename.
  8. There are two other Books/Namespaces that need all their image files copied over to Owiki. We have done the OpenCPN User Manual images.

3. Copy all of a Books/Namespace Text(HTML) files to the Owiki.

(Note Drew completed 2 1/2 books (Developer Pages have not all been created) and the O User Manual is being done by Rick and Fabbian.)

  1. Open one of the old books in your browser, say Developer Manual.
  2. This page has the Table of Contents which is automatically generated. There no text to copy.
  3. Select the next page down Developer Guide. This page has HTML that needs to be copied. We want to copy all of it, but not the HTML outside the Book. We have to be careful about that.
  4. Highlight just the wiki text & Copy to clipboard (Ctrl+C).
  5. Then in a new browser Tab, log into the Owiki temporary website and open the exact same page in Owiki, We know the Owiki Developer Manual page has the TOC which is automatically generated by the Indexmenu Plugin, so we must navigate to the first page that requires migration of HTML text, which is Developer Guide
  6. In the first page with HTML text that needs migration, Developer Guide, please note that I have already “Created” this page by inserting some Dokuwiki internal page link code in the preceding first page “Developer Manual”. I will explain in detail later.
  7. Now in the Developer Guide page I have already inserted Dokuwiki code to “Create” some sub-pages. Some of these links are Green and some are red. The red links do not yet have a page “created” which requires some extra steps after you click on the red link.
  8. We will take a brief look at the Dokuwiki Code on this page later.
  9. I don't want you to change anything yet, in fact I want you to leave those links at the top of the page, when you paste the HTML on your clipboard.
  10. We're going to look at the Dokuwiki Code on this page. Select “DW Edit” from the right menu bar.
  11. You will now see the code for the links at the top, along with the Title and above that which is the hard coded indexmenu sorting order for the Indexmenu Plugin (right hand navigation TOC).
  12. Now select Save and we are back at the normal View page.
  13. Now select from the right hand menu “Edit this Page”. There will be a pause, wait as the other CK Editor (HTML editor) comes up. It should have a double row menu and at the bottom a “DW Edit” button to switch editors. You are now in the CK Editor the HTML Editor.
  14. You can now put your cursor under the Title and Page Links, making sure the “Unordered List” Icon at the top is unselected and you are not in “unordered list” mode.
  15. Now you can finally “Paste” Ctrl-V the HTML text that is in your clipboard into the correct Owiki page (while in CK Editor is very important).
  16. The text may not be perfect, but you should see the images because the links are all referencing the Old website.
  17. Pick “Save” to save the page.
  18. Now you can pick “DW Edit” if you want to edit the page using Dokuwiki format.
  19. See the Dokuwiki Syntax, also we are making Editor User Manual Notes. These may explain the structure of Dokuwiki better. We are trying to improve this page and simplify.
  20. You can also use CK Edit for your editing. There are some pros and cons to both. I would suggest “Saving” the page before going to the other editor.

4. Check Formatting Syntax and Improve text and legibility

  1. We've noticed that CHK Edit tends to have a cleaner WYSIWYG with more selections. Some of those selections don't translate too well into Dokuwiki, so lets try to identify what is problematical below.
  2. I've noticed that when the //italic// is not properly begun or terminated, the entire document text following becomes changed, bold or italic or whatever. Look for incorrect syntax where the change occurs.
  3. Generally it's better in DW Edit, not to use too many new line // commands, they can mess stuff up and make it harder. Also going from CK Editor to DW Editor, it appears sometimes creates a lot of new line // commands and bunches up lines eliminating white space. I don't like this tendency.

5. Redirect media links. Check all media links on each page.

  1. Media links always start with {{ and end with }}
  2. If the link has http://opencpn.org/ocpn/ then it should be redirected to become an internal link using one of the media directory pathnames, starting with the main namespace “opencpn” taking the form
{{opencpn:manual:filename.png}}

The “Media Manager” will assist with finding files and uploading to the correct directory.

Media Manager

  1. Media Manager
  2. Upload files for Download Links
  3. Upload Screenshots & Images

See File Structure Please note the destination Namespaces for Links, Screenshots and Images!

After pasting the text into a page and saving, the image links will have to be changed and redirected to the proper image which will be found in one of the media directories. See File Structure

After migration of the text into the O Dokuwiki page, the links will likely be pointing to some other location and have to be redirected manually using DW Edit. See File Structure

For upload and reviewing images. Please use the correct namespaces. Each Book has its own namespace (see above). Dokuwiki Media Manager Link Docuwiki Fullscreen Media Manager wiki

6. Redirect internal links. Check all internal links on each page.

  1. Internal & External page links always start with [[ and end with ]]
  2. If the link has http://opencpn.org/ocpn/ then it should be redirected to become an internal link using one of the internal pathnames & files, starting with the main namespace “opencpn” taking the form
[[opencpn:(book):(namespace1):(namespace2):(filename.txt)|(TOC Title)]]
  1. The “book” is one of 4 choices: “opencpn_user_manual”, “supplementary_hardware”, “supplementary_software”, “developer_manual”. There should not be any other choice!
  2. The “namespaces” uses should conform to the file structure of the book exactly, or Dokuwiki will start creating new paths and sub-directories that screw up Indexmenu and the left navigation TOC.
  3. To redirect Links, use several tabs in your browser:
    1. View an Owiki page with external links (see the blue globe) which needs to be redirected using DW Edit eg: Help? with link to Getting Started
    2. This link is external & pointed to the old website: http://opencpn.org/ocpn/getting_started Right click on the link and open a new browser Tab for the old Dokuwiki page Getting Started.
    3. Open the Owiki version of the page. Right-click on Owiki top You are here: “Opencpn” to open a new browser tab and Navigate to the new Owiki Getting Started page.
    4. Highlight the last part of the URL, after the equal sign = "opencpn:opencpn_user_manual:getting_started" Copy to clipboard Ctrl+C.
    5. Click on the Editing Owiki page Help? Click on DW Edit. Highlight the external link "http://opencpn.org/ocpn/getting_started" and Paste Ctrl+V the new Owiki internal link over it so the link becomes [[opencpn:opencpn_user_manual:getting_started]]
    6. Save the page.
    7. Check the link.

There are many other methods of doing this, including just typing. This way is reliable. The media links are a similar exercise, but the pathname is much shorter and easier to remember and type and we have the Media Manager.

7. Pathnames & Namespaces - Portability.

<quote> As long as every path begins with the book namespace [[opencpn:]] we will still have a portable manual.</quote>

See File Structure More Recent!!!

Which raises a question because we have 4 Books/Namespaces under the namespace “opencpn”. We would like the entire thing to be portable. I do not know the consequences if we were to shorten the paths by eliminating that namespace, (and right now I am not interested in finding out!)

Also our Indexmenu Plugin (the navigation TOC to the right) relies on a page called “sidemenu” which is hidden but located under the “opencpn” namespace. I do not know if shortening the “pathname” would affect the operation, but I expect that all four books would not be as visible (perhaps). I'd have to think about it and do some experiments. In short, it is not simple. “ I think that until proven otherwise, we should include “opencpn” with all of the “pathnames” please. For the four “books” / “namespaces” we would then continue to use: 

**Internal Links**
[[opencpn:opencpn_user_manual:____]]
[[opencpn:supplementary_hardware:____]]
[[opencpn:supplementary_software:____]]
[[opencpn:developer_manual:_____]]
**
Media Links**
{{opencpn:manual:____}}
{{opencpn:hardware:____}}
{{opencpn:software:____}}
{{opencpn:dev:_____}}

I think at some point I will do a FIND + SED search to remove the leading colon eg [[:opencpn:__]]. So continue to use just 

[[opencpn:opencpn_user_manual:___]]

without the initial leading colon please.

8. Table of Contents - Indexmenu Plugin & File Structure creates the TOC

  1. Create Pages in the Correct Location with the correct path
  2. In Dokuwiki, the file structure/location IS the TOC Index, because Indexmenu Plugin uses the file structure to create the Table of Contents (TOC)!!!
  3. This is very different than the Drupal 6 approach which allows a Book to have a “File location & structure” different than what is shown in the “Outline” or TOC that is presented!
  4. In Dokuwiki, our File Structure must follow the TOC that we want!!

Therefore pay attention when creating new pages because the exact pathname used will affect the TOC!

We have decided not to have any “Footer” so please delete any footer code including 

{{:opencpn:logo.png?nolink&32x32}}

or references to Table of Contents, on every page.

10. Final Check of Formatting Syntax. Improve text and legibility

12. Done

Frequent Use Operations